<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>OnExit</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>OnExit</h1>

<p>Specifies a <a href="Gosub.htm">subroutine</a> or <a href="../Functions.htm">function</a> to run  automatically when the script exits.</p>

<pre class="Syntax">OnExit [, Label]
OnExit(Func [, AddRemove])  <em>; Requires <span class="ver">[v1.1.20+]</span></em></pre>
<h3>Parameters</h3>
<dl>

  <dt>Label</dt>
  <dd><p>If omitted, any previously registered label is unregistered. Otherwise, specify the name of the <a href="../misc/Labels.htm">label</a> whose contents will be executed (as a new <a href="../misc/Threads.htm">thread</a>) when the script exits by any means.</p></dd>
  
  <dt>Func</dt>
  <dd><p>A function name or <a href="../objects/Functor.htm">function object</a> to call when the script is exiting. The function can optionally define parameters as shown below. If an OnExit function returns a non-zero integer, the script does not exit. Otherwise, the script exits after all registered functions are called.</p>
  <pre class="Syntax">ExitFunc(<a href="#ExitReason">ExitReason</a>, <a href="ExitApp.htm">ExitCode</a>)</pre></dd>
  
  <dt>AddRemove</dt>
  <dd><p>One of the following values:<br>
  <strong>1</strong> (the default): Call the function after any previously registered functions.<br>
  <strong>-1</strong>: Call the function before any previously registered functions.<br>
  <strong>0</strong>: Do not call the function.</p>
  <p>If a label (subroutine) has been registered, it is always called first.</p></dd>

</dl>

<h3>Remarks</h3>
<p><strong>IMPORTANT:</strong> Since the specified subroutine is called instead of terminating the script, that subroutine must use the <a href="ExitApp.htm">ExitApp</a> command if termination is desired. <span class="ver">[v1.1.20+]:</span> New scripts should use a function instead of a subroutine -- this reduces the risk of accidentally creating a script which can't be exited, and ensures that the exit code passed to Exit or ExitApp is preserved.</p>
<p><span class="ver">[v1.1.20+]:</span> Any number of OnExit functions can be registered. If a label (subroutine) is also registered, the functions are called after the subroutine calls <a href="ExitApp.htm">ExitApp</a>. An OnExit function usually should not call ExitApp; if it does, the script terminates immediately.</p>
<p>The OnExit subroutine is called when the script exits by any means (except when it is killed by something like &quot;End Task&quot;). It is also called whenever the <a href="_SingleInstance.htm">#SingleInstance</a> and <a href="Reload.htm">Reload</a> commands ask a previous instance to terminate.</p>
<p>A script can detect and optionally abort a system shutdown or logoff via <code><a href="OnMessage.htm#shutdown">OnMessage(0x11, &quot;WM_QUERYENDSESSION&quot;)</a></code>.</p>
<p>The OnExit <a href="../misc/Threads.htm">thread</a> does not obey <a href="_MaxThreads.htm">#MaxThreads</a> (it will always launch when needed). In addition, while it is running, it cannot be interrupted by any <a href="../misc/Threads.htm">thread</a>, including <a href="../Hotkeys.htm">hotkeys</a>, <a href="Menu.htm">custom menu items</a>, and <a href="SetTimer.htm">timed subroutines</a>. However, it will be interrupted (and the script will terminate) if the user chooses Exit from the tray menu or main menu, or the script is asked to terminate as a result of <a href="Reload.htm">Reload</a> or <a href="_SingleInstance.htm">#SingleInstance</a>. Because of this, the OnExit subroutine should be designed to finish quickly unless the user is aware of what it is doing.</p>
<p>If the OnExit <a href="../misc/Threads.htm">thread</a> encounters a failure condition such as a runtime error, the script will terminate. This prevents a flawed OnExit subroutine from making a script impossible to terminate.</p>
<p>If the OnExit subroutine was launched due to an <a href="Exit.htm">Exit</a> or <a href="ExitApp.htm">ExitApp</a> command that specified an exit code, in v1.1.19 and earlier that code is ignored and no longer available. In <span class="ver">[v1.1.20+]</span> the initial exit code is used unless overridden by calling <a href="ExitApp.htm">ExitApp</a> with a new exit code.</p>
<p>Whenever the OnExit subroutine is called by an exit attempt, it starts off fresh with the default values for settings such as <a href="SendMode.htm">SendMode</a>. These defaults can be changed in the <a href="../Scripts.htm#auto">auto-execute section</a>.</p>
<p>The built-in variable <strong>A_ExitReason</strong> is blank unless the OnExit subroutine  is currently running or has been called at least once by a prior exit attempt. If not blank, it is one of the following words:</p>
<table class="info" id="ExitReason">
  <tr>
    <td>Logoff</td>
    <td><a name="logoff"></a>The user is logging off.</td>
  </tr>
  <tr>
    <td>Shutdown</td>
    <td>The system is being shut down or restarted, such as by the <a href="Shutdown.htm">Shutdown</a> command.</td>
  </tr>
  <tr>
    <td>Close</td>
    <td>The script was sent a WM_CLOSE or WM_QUIT message, had a critical error, or is being closed in some other way. Although all of these are unusual, WM_CLOSE might be caused by <a href="WinClose.htm">WinClose</a> having been used on the script's main window. To prevent this, dismiss the main window with <code>Send, !{F4}</code>.</td>
  </tr>
  <tr>
    <td>Error</td>
    <td>A runtime error  occurred in a script that has no hotkeys and that is not <a href="_Persistent.htm">persistent</a>. An example of a runtime error is <a href="Run.htm">Run/RunWait</a> being unable to launch the specified program or document.</td>
  </tr>
  <tr>
    <td>Menu</td>
    <td>The user selected Exit from the main window's menu or from the standard tray menu.</td>
  </tr>
  <tr>
    <td>Exit</td>
    <td>The <a href="Exit.htm">Exit</a> or <a href="ExitApp.htm">ExitApp</a> command was used (includes <a href="Menu.htm">custom menu items</a>).</td>
  </tr>
  <tr>
    <td>Reload</td>
    <td>The script is being reloaded via the <a href="Reload.htm">Reload</a> command or menu item.</td>
  </tr>
  <tr>
    <td>Single</td>
    <td>The script is being replaced by a new instance of itself as a result of <a href="_SingleInstance.htm">#SingleInstance</a>.</td>
  </tr>
</table>

<h3>Related</h3>
<p><a href="OnMessage.htm">OnMessage()</a>, <a href="RegisterCallback.htm">RegisterCallback()</a>, <a href="OnClipboardChange.htm">OnClipboardChange</a>, <a href="ExitApp.htm">ExitApp</a>, <a href="Shutdown.htm">Shutdown</a>, <a href="_Persistent.htm">#Persistent</a>, <a href="../misc/Threads.htm">Threads</a>, <a href="Gosub.htm">Gosub</a>, <a href="Return.htm">Return</a>, <a href="Menu.htm">Menu</a></p>

<h3 id="Examples">Examples</h3>
<p>The following examples use <a href="_Persistent.htm">#Persistent</a> to prevent the script from exiting automatically. After running the script, right click the tray icon and click <em>Exit</em> to test the OnExit subroutine or function. Then click "Yes" to terminate the script or "No" to keep it running.</p>
<pre class="NoIndent">#Persistent
OnExit, ExitSub
return

ExitSub:
if A_ExitReason not in Logoff,Shutdown  <em>; Avoid spaces around the comma in this line.</em>
{
    MsgBox, 4, , Are you sure you want to exit?
    IfMsgBox, No
        return
}
ExitApp  <em>; A script with an OnExit subroutine will not terminate unless the subroutine uses ExitApp.</em></pre>
&nbsp;
<pre class="NoIndent">#Persistent

<em>; Register a function to be called on exit:</em>
OnExit("ExitFunc")

<em>; Register an object to be called on exit:</em>
OnExit(<a href="ObjBindMethod.htm">ObjBindMethod</a>(MyObject, "Exiting"))

ExitFunc(ExitReason, ExitCode)
{
    if ExitReason not in Logoff,Shutdown
    {
        MsgBox, 4, , Are you sure you want to exit?
        IfMsgBox, No
            return 1  <em>; OnExit functions must return non-zero to prevent exit.</em>
    }
    <em>; Do not call ExitApp -- that would prevent other OnExit functions from being called.</em>
}

class MyObject
{
    Exiting()
    {
        MsgBox, MyObject is cleaning up prior to exiting...
        <em>/*
        this.SayGoodbye()
        this.CloseNetworkConnections()
        */</em>
    }
}</pre>

</body>
</html>
